[#1220] Preserve documentation versions in PDF links - #387

praise: The version selection is scoped the right way: a configured version never leaks to another component.

• targetComponent.equals(component) ? docVersion : null (AsciidocToPdfMojo.java:264) keeps docVersion to this project's component, pinned by testOtherComponentDoesNotInheritProjectVersion.
• containsKey (AsciidocToPdfMojo.java:262) is the right test for an empty entry: Maven 3.9.16 binds <openam/> as openam -> null, and that stays unversioned.
• The 4-argument preparePdfSource / convertXrefsForPdf overloads delegate with null / emptyMap(), so existing callers keep the unversioned links.

issue (blocking): Antora's versionless token _ in an explicit resource ID becomes a literal /_/ path segment.

commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojo.java:191, :252, :266

Antora (3.1.15, the site's pin) spells the versionless version _: parse-resource-id.js maps _@opendj::index.adoc to version "", and the HTML page links to /opendj/index.html. Here explicitVersion = "_" (:252) gives versionPrefix = "_/" (:266), so the PDF gets <site>/opendj/_/index.html. The site never publishes a _ directory: tag versions are <major>.<minor> (versions-from-tags.js) and the branch is unversioned. The link is a 404.

private static final Pattern RESOURCE_ID_PATTERN =
        Pattern.compile("(?:([^:/@$]+)@)?(?:([^:/@$]+):)?([^:/@$]*):([^:@$]+)");
// ...
explicitVersion = id.group(1);
// Antora spells the versionless component version "_"
if ("_".equals(explicitVersion)) {
    explicitVersion = "";
}

The Javadoc at :201-202 changes to match: "an explicit _ version selects the unversioned site". This rule covers explicit versions only. The docVersion / componentDocVersions values come from the POM, not from Antora syntax, so they keep the empty-value rule.

issue (blocking): The README and the test document xref:@opendj::index.adoc[Current] as the explicit unversioned target, and Antora rejects that resource ID.

commons/doc-maven-plugin/README.md:804-806, commons/doc-maven-plugin/src/test/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojoTest.java:87, :92

The same .adoc sources feed the antora goal. AntoraMojo.convertXrefsToAntora (AntoraMojo.java:150-162) only rewrites ../, ./ and /, so @opendj::index.adoc reaches Antora unchanged. Antora's RESOURCE_ID_RX needs a non-empty version before @, so parseResourceId returns undefined on 3.1.9 and 3.1.15. The HTML page renders an unresolved xref and logs "target of xref not found", while the PDF link works. An author who follows the README breaks the site page.

README :804-805:

An empty map entry or Antora's versionless token `_` (`xref:_@opendj::index.adoc[Current]`)
selects the unversioned site.

Test: at :87, change xref:@opendj::index.adoc[Current] to xref:_@opendj::index.adoc[Current]. The expected value at :92 stays the same. After the pattern change above, also pin the invalid form:

assertThat(AsciidocToPdfMojo.convertXrefsForPdf("xref:@opendj::index.adoc[Current]",
        SITE, "openam", "how-to", "15.2", Collections.emptyMap()))
        .isEqualTo("xref:@opendj::index.adoc[Current]");

suggestion (non-blocking): No test passes an empty or null componentDocVersions value, so the README's "empty map entry selects the unversioned site" is unpinned.

commons/doc-maven-plugin/src/test/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojoTest.java:70, :83-84, :113, :135

Maven binds <openam/>, <openam></openam> and a blank value as openam -> null. Two mutants survive all 16 tests: get(...) != null instead of containsKey at AsciidocToPdfMojo.java:262, and a fallback to docVersion for "". Both produce /openam/15.2/... for an entry that should be unversioned.

@Test
public void testEmptyComponentEntrySelectsUnversionedSite() {
    Map<String, String> versions = new HashMap<>();
    versions.put("openam", null); // what Maven binds for <openam/>
    versions.put("opendj", "");
    assertThat(AsciidocToPdfMojo.convertXrefsForPdf(
            "xref:reference:page.adoc[A] xref:opendj::index.adoc[B]",
            SITE, "openam", "how-to", "15.2", versions)).isEqualTo(
            "link:" + SITE + "/openam/reference/page.html[A] "
                    + "link:" + SITE + "/opendj/index.html[B]");
}

Pin: this case fails for both mutants.

issue (non-blocking): An explicit version on a page in the same module, xref:4.9@page.adoc[...], is not converted.

commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojo.java:191, commons/doc-maven-plugin/README.md:798-799

Antora accepts this form (current component and module, version 4.9). RESOURCE_ID_PATTERN needs a : before the page, so the xref is left as it is, and the PDF gets an xref to a document that does not exist. This contradicts the README rule that an explicit Antora version takes precedence. The behaviour is the same as at the base, and no consumer source uses the form today.

Or: narrow the README rule to resource IDs that name a module, and add a test for xref:4.9@page.adoc[x] that shows the chosen behaviour.

suggestion (non-blocking): No test exercises the Maven wiring of docVersion and componentDocVersions. The execute test sets both fields by reflection.

commons/doc-maven-plugin/src/test/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojoTest.java:133-150

setParameter uses Field.setAccessible. If the docVersion property is renamed or @Parameter is removed from componentDocVersions, every test stays green while -DdocVersion=15.2 and the POM map are silently ignored. AntoraMojoTest:46-51 already drives a mojo from a test POM. Add a POM under src/test/resources/asciidoc-to-pdf/pom.xml, copied from antora/pom.xml, with <docVersion>15.2</docVersion> and <componentDocVersions><opendj>4.10</opendj><openam/></componentDocVersions>, and this test in an AbstractMojoTestCase subclass (not run by this review):

@Test
public void testPomConfigurationReachesVersionParameters() throws Exception {
    File pom = getTestFile("src/test/resources/asciidoc-to-pdf/pom.xml");
    AsciidocToPdfMojo mojo = (AsciidocToPdfMojo) lookupMojo("asciidoc-to-pdf", pom);
    configureMojo(mojo, "doc-maven-plugin", pom);
    assertThat(getVariableValueFromObject(mojo, "docVersion")).isEqualTo("15.2");
    @SuppressWarnings("unchecked")
    Map<String, String> versions = (Map<String, String>) getVariableValueFromObject(mojo, "componentDocVersions");
    assertThat(versions).containsEntry("opendj", "4.10").containsKey("openam");
}

Pin: renaming the property or dropping @Parameter makes this test fail.

nitpick (non-blocking): The new section comes after the README's license footer.

commons/doc-maven-plugin/README.md:762, :745-759

It follows the * * * rule, the CDDL notice and "Copyright 2012-2015 ForgeRock AS.", so it renders below the license block and nests under "# Alternative Branding & Common Content" (:677). Move it above :745, either as a # chapter or under "# ForgeRock Doc Maven Plugin Features".

nitpick (non-blocking): The README adds 57 lines but no "Portions copyright 2026 3A Systems, LLC." line.

commons/doc-maven-plugin/README.md:754-759

The footer's own CDDL notice asks for this line. No other README in the repo has one, so leaving it out follows the existing practice.

praise: The parser fix is narrow and its regression rows really pin it.

• _ is normalised only for the explicit xref version (AsciidocToPdfMojo.java:256-258), so configured values stay literal site paths (testConfiguredVersionsAreLiteralSitePaths).
• With AsciidocToPdfMojo.java reverted to ee42bdc and the head's tests, exactly testEmptyExplicitVersionIsNotAnAntoraResourceId and testExplicitVersionOverridesConfiguredComponentVersion go red (18/20 stay green); at the head the class is 20/20.
• testMavenUserPropertySelectsHistoricalVersion resolves docVersion through the plugin descriptor, so it pins the property name.

issue (non-blocking): The configuration tests do not pin the @Parameter annotation on componentDocVersions.

commons/doc-maven-plugin/src/test/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojoConfigurationTest.java:52-89, commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojo.java:95-96

lookupConfiguredMojo (harness 3.3.0) applies the raw <plugin><configuration> and sets fields by name, without checking the descriptor; Maven 3.9.16 (DefaultLifecycleExecutionPlanCalculator.finalizeMojoConfiguration) keeps only the children the descriptor declares. With @Parameter removed, the generated plugin.xml has no componentDocVersions and all three configuration tests stay green (3/3), while a real build drops the POM map and every other component's links go unversioned. The description says these tests cover POM versions; for the map they do not.

public void testComponentDocVersionsIsADescriptorParameter() throws Exception {
    assertTrue(newMojoExecution("asciidoc-to-pdf").getMojoDescriptor()
            .getParameterMap().containsKey("componentDocVersions"));
}

Pin: the case reads the generated descriptor, so removing the annotation turns it red (MojoDescriptor.getParameterMap() exists in maven-plugin-api 3.9.16; the case itself was not compiled in this review).

suggestion (non-blocking): No test leaves componentDocVersions unconfigured, so its = Collections.emptyMap() default is unpinned.

commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojo.java:96, :268

Every case supplies the map: the test POM always keeps <componentDocVersions>, the execute test sets it by reflection, the 4-argument overloads pass emptyMap(). With the initializer removed, the module's tests stay 23/23 green, but a POM without the element — every current consumer — gets a null field and an NPE at componentDocVersions.containsKey on the first xref without an explicit version.

public void testAbsentMapKeepsOtherComponentsUnversioned() throws Exception {
    MavenProject project = readProject();
    Xpp3Dom configuration = (Xpp3Dom) project.getBuildPlugins().get(0).getConfiguration();
    configuration.removeChild(configuration.getChild("componentDocVersions"));
    AsciidocToPdfMojo mojo = (AsciidocToPdfMojo) lookupConfiguredMojo(project, "asciidoc-to-pdf");
    FileUtils.writeStringToFile(new File(mojo.getAsciidocBuildSourceDirectory(), "how-to/page.adoc"),
            "xref:reference:page.adoc[A] xref:opendj::index.adoc[B]", StandardCharsets.UTF_8);
    mojo.execute();
    assertThat(new File(mojo.getPdfSourceDirectory(), "how-to/page.adoc")).hasContent(
            "link:https://doc.openidentityplatform.org/openam/15.2/reference/page.html[A] "
                    + "link:https://doc.openidentityplatform.org/opendj/index.html[B]");
}

Pin: without the initializer execute() throws the NPE and the case goes red.

issue (non-blocking): The archive workflow does not say the rebuild needs a doc-maven-plugin release that has docVersion.

commons/doc-maven-plugin/README.md:797-803

OpenDJ release tags pin the plugin through ${commons.version} (5.2.0: 3.2.2; 4.10.2: 2.4.1), and no released version up to 3.2.2 has the parameter. Maven ignores a -DdocVersion that no mojo reads, without a warning, so the rebuilt PDF keeps the unversioned links and replaces the archive unchanged. OpenAM 15.2.2, OpenIG 6.2.0 and OpenIDM 7.1.2 declare the plugin without a version, so there the workflow works once a release with this change exists.

The rebuild needs a doc-maven-plugin release that supports `docVersion` (the
first release after 3.2.2). Release tags that pin the plugin through
`${commons.version}`, such as OpenDJ 4.10.2 and 5.x, must raise that plugin
version for the rebuild; otherwise Maven ignores `-DdocVersion` without a
warning and the PDF keeps its unversioned links.

question (non-blocking): Should a component-qualified xref to this project's own component without a version follow docVersion?

commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojo.java:268-270, commons/doc-maven-plugin/src/test/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojoTest.java:72-75

With docVersion=15.2, xref:openam:ROOT:index.adoc (or xref:openam:reference:x.adoc) in OpenAM becomes /openam/15.2/... in the PDF, as the test pins; Antora 3.1.15 resolves a component-qualified ID without a version to the latest version, so the site page built from the same 15.2 source links to /openam/.... No current OpenAM, OpenDJ, OpenIG or OpenIDM source uses this form, so it is Minor either way. If the PDF should match the site, apply docVersion only when the resource ID names no component (relative ../ xrefs keep it) and flip the test:

String explicitVersion = null;
boolean namedComponent = false;
// ... in the resource-ID branch, after targetComponent is set:
namedComponent = id.group(2) != null;
// ... at :270:
        : targetComponent.equals(component) && !namedComponent ? docVersion : null;

If archived self-links are intended, say in rule 3 (README.md:784) that the PDF deliberately differs from the site for this form.

suggestion (non-blocking): Normalise configured version values before they become a path segment.

commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojo.java:272, :213

-DdocVersion=15.2/ gives /openam/15.2//reference/..., and -DdocVersion="15.2 " a path with a space; siteUrl gets its trailing slashes stripped at :213, version values nothing. POM element text already arrives trimmed (Maven 3.9.16 POM reader), so whitespace comes only from -D; slashes from any route.

String trimmed = version == null ? "" : version.trim().replaceAll("^/+|/+$", "");
String versionPrefix = trimmed.isEmpty() ? "" : trimmed + "/";

This is a no-op for explicit xref versions (RESOURCE_ID_PATTERN at :192 excludes /, XREF_PATTERN at :190 excludes whitespace) and for _, so testConfiguredVersionsAreLiteralSitePaths is unaffected (not run in this review).

suggestion (non-blocking): Say that a project property named docVersion also sets the parameter.

commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojo.java:87, commons/doc-maven-plugin/README.md:762

Maven resolves ${docVersion} from user, system and then project properties, inherited ones included, so a <properties><docVersion> defined for another purpose now versions every own-component PDF link. None exists today in OpenAM, OpenDJ, OpenIG, OpenIDM, OpenICF or the JEE agents; the unprefixed name matches siteUrl and antoraComponent, so keeping it is reasonable.

`docVersion` is also available as the Maven property `-DdocVersion=15.2`; a
`docVersion` project property, including one inherited from a parent POM, sets it too.

nitpick (non-blocking): The precedence example names OpenDJ 4.9, which the site does not publish.

commons/doc-maven-plugin/README.md:782

The site publishes OpenDJ-4.10.2 as 4.10, and README.md:804-805 says not to select an unpublished version path; with 4.10 the example stays copyable.

   `xref:4.10@opendj:install-guide:index.adoc[Install]`.

praise: This round answers the previous review's items in both the tests and the README.

• testComponentDocVersionsIsADescriptorParameter asserts that the asciidoc-to-pdf descriptor lists componentDocVersions.
• testAbsentMapKeepsOtherComponentsUnversioned removes <componentDocVersions> and asserts that xref:opendj::index.adoc stays at /opendj/index.html.
• README.md:804-807 names the ${commons.version} pin in OpenDJ 4.10.2 and 5.2.0 and says that the rebuild must select a plugin release that supports these options.